全局化配置 ConfigProvider - Ant Design

使用

ConfigProvider 使用 React 的 context 特性，只需在应用外围包裹一次即可全局生效。

tsx

import React from 'react';
import { ConfigProvider } from 'antd';

// ...
const Demo: React.FC = () => (
  <ConfigProvider direction="rtl">
    <App />
  </ConfigProvider>
);

export default Demo;

内容安全策略（CSP）

部分组件为了支持波纹效果，使用了动态样式。如果开启了 Content Security Policy (CSP)，你可以通过 csp 属性来进行配置：

tsx

<ConfigProvider csp={{ nonce: 'YourNonceCode' }}>
  <Button>My Button</Button>
</ConfigProvider>

代码演示

API

参数	说明	类型	默认值	版本
componentDisabled	设置 antd 组件禁用状态	boolean	-	4.21.0
componentSize	设置 antd 组件大小	`small` \| `medium` \| `large`	-
csp	设置 Content Security Policy 配置	{ nonce: string }	-
direction	设置文本展示方向。示例	`ltr` \| `rtl`	`ltr`
getPopupContainer	弹出框（Select, Tooltip, Menu 等等）渲染父节点，默认渲染到 body 上。	`(trigger?: HTMLElement) => HTMLElement \| ShadowRoot`	() => document.body
getTargetContainer	配置 Affix、Anchor 滚动监听容器。	`() => HTMLElement \| Window \| ShadowRoot`	() => window	4.2.0
iconPrefixCls	设置图标统一样式前缀	string	`anticon`	4.11.0
locale	语言包配置，语言包可到 antd/locale 目录下寻找	object	-
popupMatchSelectWidth	下拉菜单和选择器同宽。默认将设置 `min-width`，当值小于选择框宽度时会被忽略。`false` 时会关闭虚拟滚动	boolean \| number	-	5.5.0
popupOverflow	Select 类组件弹层展示逻辑，默认为可视区域滚动，可配置成滚动区域滚动	'viewport' \| 'scroll'	'viewport'	5.5.0
prefixCls	设置统一样式前缀	string	`ant`
renderEmpty	自定义组件空状态。参考空状态	function(componentName: string): ReactNode	-
theme	设置主题，参考定制主题	Theme	-	5.0.0
variant	设置全局输入组件形态变体	`outlined` \| `filled` \| `borderless`	-	5.19.0
virtual	设置 `false` 时关闭虚拟滚动	boolean	-	4.3.0
warning	设置警告等级，`strict` 为 `false` 时会将废弃相关信息聚合为单条信息	{ strict: boolean }	-	5.10.0
~~autoInsertSpaceInButton~~	Button 自动空格配置，请使用 `button={{ autoInsertSpace: boolean }}` 替代	boolean	-	-
~~dropdownMatchSelectWidth~~	下拉菜单和选择器是否同宽，请使用 `popupMatchSelectWidth` 替代	boolean	-	-

ConfigProvider.config()

设置 Modal、Message、Notification 静态方法配置，只会对非 hooks 的静态方法调用生效。

tsx

ConfigProvider.config({
  // 5.13.0+
  holderRender: (children) => (
    <ConfigProvider
      prefixCls="ant"
      iconPrefixCls="anticon"
      theme={{ token: { colorPrimary: 'red' } }}
    >
      {children}
    </ConfigProvider>
  ),
});

ConfigProvider.useConfig() 5.3.0+

获取父级 Provider 的值，如 DisabledContextProvider、SizeContextProvider。

jsx

const {
  componentDisabled, // 5.3.0+
  componentSize, // 5.3.0+
} = ConfigProvider.useConfig();

返回值	说明	类型	默认值	版本
componentDisabled	antd 组件禁用状态	boolean	-	5.3.0
componentSize	antd 组件大小状态	`small` \| `medium` \| `large`	-	5.3.0

组件配置

以下配置项用于设置对应组件的通用属性或全局效果配置，具体 API 见链接：

affix：Affix（自 6.0.0 起支持）
alert：Alert（自 5.7.0 起支持）
anchor：Anchor（自 6.0.0 起支持）
app：App（自 6.3.0 起支持）
avatar：Avatar（自 5.7.0 起支持）
badge：Badge（自 5.7.0 起支持）
borderBeam：BorderBeam（自 6.4.0 起支持）
breadcrumb：Breadcrumb（自 5.7.0 起支持）
button：Button（自 5.6.0 起支持）
calendar：Calendar（自 6.0.0 起支持）
card：Card（自 5.14.0 起支持）
cardMeta：Card.Meta（自 6.0.0 起支持）
carousel：Carousel（自 5.7.0 起支持）
cascader：Cascader（自 5.13.0 起支持）
checkbox：Checkbox（自 6.0.0 起支持）
collapse：Collapse（自 5.15.0 起支持）
colorPicker：ColorPicker（自 6.3.0 起支持）
datePicker：DatePicker（自 5.7.0 起支持）
rangePicker：RangePicker（自 5.11.0 起支持）
descriptions：Descriptions（自 5.23.0 起支持）
divider：Divider（自 5.10.0 起支持）
drawer：Drawer（自 5.10.0 起支持）
dropdown：Dropdown（自 5.11.0 起支持）
empty：Empty（自 5.23.0 起支持）
flex：Flex（自 5.10.0 起支持）
floatButton：FloatButton（自 6.0.0 起支持）
floatButtonGroup：FloatButton.Group（自 5.16.0 起支持）
form：Form（自 4.8.0 起支持）
image：Image（自 5.14.0 起支持）
input：Input（自 4.2.0 起支持）
inputNumber：InputNumber（自 5.19.0 起支持）
otp：Input.OTP（自 6.0.0 起支持）
inputPassword：Input.Password（自 6.4.0 起支持）
inputSearch：Input.Search（自 6.4.0 起支持）
textArea：Input.TextArea（自 5.15.0 起支持）
layout：Layout（自 5.7.0 起支持）
list：List（自 5.7.0 起支持）
masonry：Masonry（自 6.0.0 起支持）
menu：Menu（自 5.15.0 起支持）
mentions：Mentions（自 5.13.0 起支持）
message：Message（自 5.7.0 起支持）
modal：Modal（自 5.10.0 起支持）
notification：Notification（自 5.14.0 起支持）
pagination：Pagination（自 6.0.0 起支持）
progress：Progress（自 5.7.0 起支持）
radio：Radio（自 6.0.0 起支持）
rate：Rate（自 5.7.0 起支持）
result：Result（自 6.0.0 起支持）
ribbon：Badge.Ribbon（自 6.0.0 起支持）
skeleton：Skeleton（自 6.0.0 起支持）
segmented：Segmented（自 6.0.0 起支持）
select：Select（自 5.13.0 起支持）
slider：Slider（自 5.23.0 起支持）
switch：Switch（自 6.0.0 起支持）
space：Space（自 5.6.0 起支持）
splitter：Splitter（自 5.21.0 起支持）
spin：Spin（自 5.20.0 起支持）
statistic：Statistic（自 6.0.0 起支持）
steps：Steps（自 5.10.0 起支持）
table：Table（自 6.2.0 起支持）
tabs：Tabs（自 5.14.0 起支持）
tag：Tag（自 5.14.0 起支持）
timeline：Timeline（自 6.0.0 起支持）
timePicker：TimePicker（自 5.13.0 起支持）
tour：Tour（自 5.14.0 起支持）
tooltip：Tooltip（自 6.1.0 起支持）
popover：Popover（自 5.23.0 起支持）
popconfirm：Popconfirm（自 5.23.0 起支持）
qrcode：QRCode（自 6.0.0 起支持）
transfer：Transfer（自 5.7.0 起支持）
tree：Tree（自 6.0.0 起支持）
treeSelect：TreeSelect（自 5.19.0 起支持）
typography：Typography（自 6.4.0 起支持）
upload：Upload（自 5.27.0 起支持）
watermark：Watermark（自 6.0.0 起支持）
wave：WaveConfig（自 5.8.0 起支持）

WaveConfig

参数	说明	类型	默认值	版本
disabled	是否禁用水波纹效果	boolean	false
showEffect	自定义水波纹效果	(node: HTMLElement, info: { className, token, component }) => void	-
triggerType	触发水波纹效果的事件	`click` \| `pointerdown` \| `pointerup` \| `mousedown` \| `mouseup`	`click`	6.4.0

FAQ

如何增加一个新的语言包？

参考《增加语言包》。

为什么时间类组件的国际化 locale 设置不生效？

参考 FAQ 为什么时间类组件的国际化 locale 设置不生效？。

配置 `getPopupContainer` 导致 Modal 报错？

相关 issue：https://github.com/ant-design/ant-design/issues/19974

当如下全局设置 getPopupContainer 为触发节点的 parentNode 时，由于 Modal 的用法不存在 triggerNode，这样会导致 triggerNode is undefined 的报错，需要增加一个判断条件。

diff

<ConfigProvider
-  getPopupContainer={triggerNode => triggerNode.parentNode}
+  getPopupContainer={node => {
+    if (node) {
+      return node.parentNode;
+    }
+    return document.body;
+  }}
 >
   <App />
 </ConfigProvider>

为什么 message.info、notification.open 或 Modal.confirm 等方法内的 ReactNode 无法继承 ConfigProvider 的属性？比如 `prefixCls` 和 `theme`。

静态方法是使用 ReactDOM.render 重新渲染一个 React 根节点上，和主应用的 React 节点是脱离的。我们建议使用 useMessage、useNotification 和 useModal 来使用相关方法。原先的静态方法在 5.0 中已被废弃。

Vite 生产模式打包后国际化 locale 设置不生效？

相关 issue：#39045

由于 Vite 生产模式下打包与开发模式不同，cjs 格式的文件会多一层，需要 zhCN.default 来获取。推荐 Vite 用户直接从 antd/es/locale 目录下引入 esm 格式的 locale 文件。

prefixCls 优先级(前者被后者覆盖)

ConfigProvider.config({ prefixCls: 'prefix-1' })
ConfigProvider.config({ holderRender: (children) => <ConfigProvider prefixCls="prefix-2">{children}</ConfigProvider> })
message.config({ prefixCls: 'prefix-3' })

Change locale of components:

English中文

1
2
3
4
5
10 / page

Click to confirm

0 item

No data

0 item

No data

2026

Jun

MonthYear

Name	Age
No data

QR code expired

Uploading...

image.png

Tour

此处列出 Ant Design 中需要国际化支持的组件，你可以在演示里切换语言。